\chapter{qhash-iterator}

class QHash::iterator

QHash::iterator 为 QHash 和 QMultiHash 提供 STL 风格的非常量迭代器。更多内容...


\begin{compactitem}
\item 所有成员列表，包括继承的成员
\item 废弃的成员
\end{compactitem}

\splitLine

\section{公共成员函数}

\begin{tabular}{|l|l|}
\hline
类型	&函数名\\
\hline
& iterator()\\
\hline
const Key \& &	key() const\\
\hline
T \& &	value() const\\
\hline
bool	& operator!=(const iterator \&other) const\\
\hline
bool	& operator!=(const const\_iterator \&other) const\\
\hline
T \& & 	operator*() const\\
\hline
iterator \&	&operator++()\\
\hline
iterator	&\&operator++(int)\\
\hline
T *	& operator->() const\\
\hline
bool&	operator==(const iterator \emph{\&other}) const\\
\hline
bool&	operator==(const const\_iterator \emph{\&other}) const\\
\hline
\end{tabular}


\splitLine

\section{详细描述}

QHash 同时提供 STL-style iterators 和 Java-style iterators。STL 风格迭代器更底层，使用更笨拙；同时也稍快一些。对于已经了解 STL 的开发者来说更加熟悉。

QHash<Key, T>::iterator 用来遍历 QHash (或 QMultiHash) 并修改与特定键相关联的值（不能修改键）。如果想遍历常量 QHash，应该使用 QHash::const\_iterator。对于非常量 QHash，使用 QHash::const\_iterator 通常是也好的编程实践，除非需要在遍历时改变 QHash。常量类型的迭代器稍快一些并可以提高代码可读性。

QHash::iterator 的默认构造函数创建一个未初始化的迭代器。必须在开始遍历
前使用 QHash::begin()， QHash::end()，或 QHash::find() 等 QHash 函数初
始化它。下面是一个典型的循环，该循环打印出哈希表中的所有键值对：

\begin{cppcode}
QHash<QString, int> hash;
hash.insert("January", 1);
hash.insert("February", 2);
...
hash.insert("December", 12);

QHash<QString, int>::iterator i;
for (i = hash.begin(); i != hash.end(); ++i)
    cout << i.key() << ": " << i.value() << Qt::endl;
\end{cppcode}

与通过键的大小有序存储元素的 QMap 不同，QHash 无序存储元素。

让我们通过几个例子来了解哪些情况下可以用 QHash::iterator 而不能用 QHash::const\_iterator。下面的例子将存储在 QHash 中的每个值增加2：

\begin{cppcode}
QHash<QString, int>::iterator i;
for (i = hash.begin(); i != hash.end(); ++i)
    i.value() += 2;
\end{cppcode}

下面的例子移除所有键字符串的首字符是下划线的元素：

\begin{cppcode}
QHash<QString, int>::iterator i = hash.begin();
while (i != hash.end()) {
    if (i.key().startsWith('_'))
        i = hash.erase(i);
    else
        ++i;
}
\end{cppcode}

对 QHash::erase() 的调用从哈希表中移除迭代器所指元素，返回指向下一个元
素的迭代器。下面是另一个在遍历时移除元素的方法：

\begin{cppcode}
QHash<QString, int>::iterator i = hash.begin();
while (i != hash.end()) {
    QHash<QString, int>::iterator prev = i;
    ++i;
    if (prev.key().startsWith('_'))
        hash.erase(prev);
}
\end{cppcode}

有人会写出像下面这样的代码：

\begin{cppcode}
// WRONG
while (i != hash.end()) {
    if (i.key().startsWith('_'))
        hash.erase(i);
    ++i;
}
\end{cppcode}

然而，这会导致程序在 ++i 处崩溃，因为调用完 erase() 后，i成为悬空迭代器。

同一哈希表可以使用多个迭代器。然而，需要注意任何对 QHash 的直接修改都可能完全改变哈希表中存储的元素顺序，因为该操作可能引起 QHash 重新散列其内部数据结构。有一个例外是 QHash::erase()。该函数可以在迭代时安全调用，不会影响哈希表中元素的顺序。如果需要长时间持有迭代器，建议使用 QMap 而非 QHash。

\begin{warning}
隐式共享容器迭代器的工作方式和 STL 迭代器不完全相同。当容器的迭代器还处于活动状态时，应该避免拷贝容器。更多信息请参阅隐式共享迭代器问题。
\end{warning}
 
\begin{seeAlso}
QHash::const\_iterator，QHash::key\_iterator 和
QMutableHashIterator。
\end{seeAlso}

\section{成员函数文档}

bool iterator::operator!=(const const\_iterator \emph{\&other}) const

bool iterator::operator!=(const iterator \emph{\&other}) const

如果 \emph{other} 与本迭代器指向的元素不同，返回 \hl{true}；否则返回 \hl{false}。

\begin{seeAlso}
operator==()。
\end{seeAlso}
 

bool iterator::operator==(const const\_iterator \emph{\&other}) const

bool iterator::operator==(const iterator \emph{\&other}) const

如果 \emph{other} 与本迭代器指向相同的元素，返回 \hl{true}；否则返回 \hl{false}。



\begin{seeAlso}
operator!=()。
\end{seeAlso}

iterator::iterator()

构造一个未初始化的迭代器。

一定不要对未初始化的迭代器调用 key()，value() 和 operator++() 等函数。使用前要用 operator=() 赋值。


\begin{seeAlso}
 QHash::begin() 和 QHash::end()。
\end{seeAlso}

const Key \&iterator::key() const

以常引用返回当前元素的键。

不能直接通过迭代器改变元素的键，尽管可以通过调用 QHash::erase() 后再调用 QHash::insert() 的方式来改变键。


\begin{seeAlso}
 value()。
\end{seeAlso}

T \&iterator::value() const

返回当前元素值的可修改引用。

可以通过在赋值运算符左边使用 value() 来修改元素的值，例如：

\begin{cppcode}
if (i.key() == "Hello")
    i.value() = "Bonjour";
\end{cppcode}


\begin{seeAlso}
key() 和 operator*()。
\end{seeAlso}

T \&iterator::operator*() const

返回当前元素值的可修改引用。

同 value()。


\begin{seeAlso}
key()。
\end{seeAlso}


iterator \&iterator::operator++()

前置 \hl{++} 运算符（\hl{++i}）将迭代器向前移动到哈希表中的下一个元素并返回指向新位置元素的迭代器。

对 QHash::end() 调用该函数将导致未定义结果。


\begin{seeAlso}
operator--()。
\end{seeAlso}

iterator iterator::operator++(int)

这是一个重载函数。

后置 \hl{++} 运算符（\hl{i++}）将迭代器向前移动到哈希表中的下一个元素并返回指向旧位置元素的迭代器。

T *iterator::operator->() const

返回指向当前元素值的指针。

\begin{seeAlso}
 value()。
\end{seeAlso}
